/*
 * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package javax.naming;

import java.util.Enumeration;

/**
 * This interface is for enumerating lists returned by
 * methods in the javax.naming and javax.naming.directory packages.
 * It extends Enumeration to allow as exceptions to be thrown during
 * the enumeration.
 * <p>
 * When a method such as list(), listBindings(), or search() returns
 * a NamingEnumeration, any exceptions encountered are reserved until
 * all results have been returned. At the end of the enumeration, the
 * exception is thrown (by hasMore());
 * <p>
 * For example, if the list() is
 * returning only a partial answer, the corresponding exception would
 * be PartialResultException. list() would first return a NamingEnumeration.
 * When the last of the results has been returned by the NamingEnumeration's
 * next(), invoking hasMore() would result in PartialResultException being thrown.
 * <p>
 * In another example, if a search() method was invoked with a specified
 * size limit of 'n'. If the answer consists of more than 'n' results,
 * search() would first return a NamingEnumeration.
 * When the n'th result has been returned by invoking next() on the
 * NamingEnumeration, a SizeLimitExceedException would then thrown when
 * hasMore() is invoked.
 * <p>
 * Note that if the program uses hasMoreElements() and nextElement() instead
 * to iterate through the NamingEnumeration, because these methods
 * cannot throw exceptions, no exception will be thrown. Instead,
 * in the previous example, after the n'th result has been returned by
 * nextElement(), invoking hasMoreElements() would return false.
 * <p>
 * Note also that NoSuchElementException is thrown if the program invokes
 * next() or nextElement() when there are no elements left in the enumeration.
 * The program can always avoid this exception by using hasMore() and
 * hasMoreElements() to check whether the end of the enumeration has been reached.
 * <p>
 * If an exception is thrown during an enumeration,
 * the enumeration becomes invalid.
 * Subsequent invocation of any method on that enumeration
 * will yield undefined results.
 *
 * @author Rosanna Lee
 * @author Scott Seligman
 * @see Context#list
 * @see Context#listBindings
 * @see javax.naming.directory.DirContext#search
 * @see javax.naming.directory.Attributes#getAll
 * @see javax.naming.directory.Attributes#getIDs
 * @see javax.naming.directory.Attribute#getAll
 * @since 1.3
 */
public interface NamingEnumeration<T> extends Enumeration<T> {
    /**
     * Retrieves the next element in the enumeration.
     * This method allows naming exceptions encountered while
     * retrieving the next element to be caught and handled
     * by the application.
     * <p>
     * Note that <tt>next()</tt> can also throw the runtime exception
     * NoSuchElementException to indicate that the caller is
     * attempting to enumerate beyond the end of the enumeration.
     * This is different from a NamingException, which indicates
     * that there was a problem in obtaining the next element,
     * for example, due to a referral or server unavailability, etc.
     *
     * @return The possibly null element in the enumeration.
     * null is only valid for enumerations that can return
     * null (e.g. Attribute.getAll() returns an enumeration of
     * attribute values, and an attribute value can be null).
     * @throws NamingException                  If a naming exception is encountered while attempting
     *                                          to retrieve the next element. See NamingException
     *                                          and its subclasses for the possible naming exceptions.
     * @throws java.util.NoSuchElementException If attempting to get the next element when none is available.
     * @see java.util.Enumeration#nextElement
     */
    public T next() throws NamingException;

    /**
     * Determines whether there are any more elements in the enumeration.
     * This method allows naming exceptions encountered while
     * determining whether there are more elements to be caught and handled
     * by the application.
     *
     * @return true if there is more in the enumeration ; false otherwise.
     * @throws NamingException If a naming exception is encountered while attempting
     *                         to determine whether there is another element
     *                         in the enumeration. See NamingException
     *                         and its subclasses for the possible naming exceptions.
     * @see java.util.Enumeration#hasMoreElements
     */
    public boolean hasMore() throws NamingException;

    /**
     * Closes this enumeration.
     * <p>
     * After this method has been invoked on this enumeration, the
     * enumeration becomes invalid and subsequent invocation of any of
     * its methods will yield undefined results.
     * This method is intended for aborting an enumeration to free up resources.
     * If an enumeration proceeds to the end--that is, until
     * <tt>hasMoreElements()</tt> or <tt>hasMore()</tt> returns <tt>false</tt>--
     * resources will be freed up automatically and there is no need to
     * explicitly call <tt>close()</tt>.
     * <p>
     * This method indicates to the service provider that it is free
     * to release resources associated with the enumeration, and can
     * notify servers to cancel any outstanding requests. The <tt>close()</tt>
     * method is a hint to implementations for managing their resources.
     * Implementations are encouraged to use appropriate algorithms to
     * manage their resources when client omits the <tt>close()</tt> calls.
     *
     * @throws NamingException If a naming exception is encountered
     *                         while closing the enumeration.
     * @since 1.3
     */
    public void close() throws NamingException;
}
